/*
 * Copyright 2008 Max Kugland
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package org.splink.resource {
	import org.splink.resource.resourcebundles.resourcebundle.fonts.FontData;

	import flash.display.DisplayObject;
	import flash.media.Sound;

	/**
	 * After the xml has been loaded and processed by <code>ResourceProcessor</code> 
	 * <code>IResourceProvider</code> implementations provide access to assets and fonts 
	 * which are defined within a resourcebundles xml file. The structure of the 
	 * resourcebundles xml file is predefined via resourcebundles.dtd.
	 * 
	 * @author Max Kugland
	 */	
	public interface IResourceProvider {

		/**
		 * Returns the <code>DisplayObject</code> representing a loaded swf defined
		 * within the library node of the resourcebundle xml.
		 * 
		 * @param the id of the code library whose display is returned
		 * @return the loaded code librarie's <code>DisplayObject</code>
		 */
		function getLibraryById(id : String) : DisplayObject;

		/**
		 * Returns a <code>FontData</code> instance which corresponds to the given type.
		 * Available types can be found within the resourcebundle xml' font nodes 
		 * 
		 * @param type the type of the <code>FontData</code> to return
		 * @return a <code>FontData</code> instance, or if unavailible null is returned
		 */
		function getFontDataByType(type : String) : FontData;

		/**
		 * Asset classes can be retrieved by their id. The class of the requested asset is internally 
		 * instantiated and the resulting <code>DisplayObject</code> is returned. If no matching 
		 * asset can be found for the given id or the instantiaion fails, null is returned.
		 * 
		 * @param id the id of the asset to return
		 * @return the asset <code>DisplayObject</code>. If it is not availible, null is returned
		 */
		function getAssetById(id : String) : DisplayObject;
		
		/**
		 * Sound assets comply to the same rules as visible assets do. 
		 * 
		 * @param id the id of the <code>Class</code> object to return
		 * @return the asset <code>Sound</code>. If it is not availible, null is returned
		 */
		function getSoundAssetById(id : String) : Sound;
		
		/**
		 * Files can be retrieved by their id. The class of the requested file is internally 
		 * instantiated and the resulting Object is returned. If no matching 
		 * file can be found for the given id or the instantiaion fails, null is returned.
		 * 
		 * @param id the id of the file to return
		 * @return the file content. If it is not availible, null is returned
		 */
		function getFileById(id : String) : *;

		/**
		 * @return the locale which is currently in use
		 */
		function get currentLocale() : String;

		/**
		 * @return an Array of available locales represented as Strings 
		 */
		function get availableLocales() : Array;

		/**
		 * @return the locale which is defined to be the default locale
		 */
		function get defaultLocale() : String;
	}
}
